Offline Maps

An object conforming to the MGLOfflineRegion protocol determines which resources are required by an MGLOfflinePack object.

MGLOfflineStorage implements a singleton (shared object) that manages offline packs and ambient caching. All of this class’s instance methods are asynchronous, reflecting the fact that offline resources are stored in a database. The shared object maintains a canonical collection of offline packs in its packs property.

Mapbox resources downloaded via this API are subject to separate Vector Tile and Raster Tile API pricing and are not included in the Maps SDK’s “unlimited” requests. See our pricing page for more information.

Related examples

See the Download an offline map example to learn how to create and register an offline pack for a defined region.

An MGLOfflinePack represents a collection of resources necessary for viewing a region offline to a local database.

To create an instance of MGLOfflinePack, use the +[MGLOfflineStorage addPackForRegion:withContext:completionHandler:] method. A pack created using -[MGLOfflinePack init] is immediately invalid.

Example

MGLOfflineStorage.shared.addPack(for: region, withContext: context) { (pack, error) in
    guard let pack = pack else {
        // If adding the pack fails, log an error to console.
        print("Error:", error?.localizedDescription ?? "unknown error adding pack at \(#file)(\(#line)) in \(#function)")
        return
    }

    // Start an MGLOfflinePack download
    pack.resume()
}

A structure containing information about an offline pack’s current download progress.

The state an offline pack is currently in.

An offline region defined by a style URL, geographic coordinate bounds, and range of zoom levels.

To minimize the resources required by an irregularly shaped offline region, use the MGLShapeOfflineRegion class instead.

Example

let northeast = CLLocationCoordinate2D(latitude: 40.989329, longitude: -102.062592)
let southwest = CLLocationCoordinate2D(latitude: 36.986207, longitude: -109.049896)
let bbox = MGLCoordinateBounds(sw: southwest, ne: northeast)

let region = MGLTilePyramidOfflineRegion(styleURL: MGLStyle.lightStyleURL, bounds: bbox, fromZoomLevel: 11, toZoomLevel: 14)
let context = "Tile Pyramid Region".data(using: .utf8)
MGLOfflineStorage.shared.addPack(for: region, withContext: context!)

Related examples

See the Download an offline map example to learn how to define an offline region to be downloaded to a user’s device.

An offline region defined by a style URL, geographic shape, and range of zoom levels.

Example

var coordinates = [
    CLLocationCoordinate2D(latitude: 45.522585, longitude: -122.685699),
    CLLocationCoordinate2D(latitude: 45.534611, longitude: -122.708873),
    CLLocationCoordinate2D(latitude: 45.530883, longitude: -122.678833)
]

let triangle = MGLPolygon(coordinates: &coordinates, count: UInt(coordinates.count))
let region = MGLShapeOfflineRegion(styleURL: MGLStyle.lightStyleURL, shape: triangle, fromZoomLevel: 11, toZoomLevel: 14)
let context = "Triangle Region".data(using: .utf8)
MGLOfflineStorage.shared.addPack(for: region, withContext: context!)

This class requires fewer resources than MGLTilePyramidOfflineRegion for irregularly shaped regions.